项目配置（Project Config）

项目是任意包含 rive.yaml 的目录。只有 name 是必需的：

rive.yaml

name: myproject

文件发现

目录中的其他内容按扩展名打包。无需维护清单。

扩展名	变成
.luau	脚本，包括协议脚本和可导入模块
.wgsl	着色器，编译为 RSTB
.rml	场景。一个项目可以在任意文件夹中包含任意数量的标记文件，它们会作为一份文档编译
.png .jpg .jpeg .webp	图像资源
其他	blob 资源，可从脚本按名称查找

这是发现源文件的方式，并不保证目录中的所有内容都会进入 .riv。资源只有在被引用时才会嵌入，引用可以是 RML 中的 file=，或脚本按名称查找。没有任何东西使用的字体或图像不会加入输出。

脚本和着色器是例外：扫描到的每个 .luau 和 .wgsl 都会编译进文件，无论是否有东西引用它们。用 exclude 可以把某个排除出去。

标记文件会一起编译，因此在一个文件中声明的 id 可以从另一个文件引用。id 不能跨文件重复，问题会报告在它所在的文件上。按阅读习惯拆分即可，例如画板放一个文件、视图模型放另一个。

点文件和点目录会被跳过，rive.yaml、output.dir 指向的内容，以及以 .riv、.rev 或 .log 结尾的内容也会被跳过。

RML 中的资源路径相对于项目：

<!-- inside <Rive>, alongside the artboards -->
<FontAsset file="Montserrat.ttf" name="Montserrat" id="0:30"/>
<ScriptAsset file="main.luau" name="main" id="0:80"/>

磁盘上的常规项目：

myproject/
  rive.yaml
  scene.rml
  main.luau
  mathutil.luau
  Montserrat.ttf
  logo.png
  build/

完整形态

rive.yaml

name: myproject
main: main
debugLevel: 0
optimizationLevel: 2

artboard:
  width: 800
  height: 600
  background: "#1D1D1D"      # 请加引号，裸 # 会开始 YAML 注释

artboards:
  main:
    width: 1920
    height: 1080

exclude:
  - docs

excludeFromRev:
  scripts:
    - "*_test"
  artboards:
    - tests/*
  assets:
    - raw_*
  contents:
    - logo

libraries:
  - ../shared_widgets

revFlavor: editable          # 或 "library"

output:
  dir: build

logs:
  file: build/rive.log
  problems: build/problems.log

键

name — 必需。也是其他项目导入本项目时使用的名称。

main — 哪个画板是文件的默认画板。不指定时，以声明的第一个为准。

debugLevel、optimizationLevel、shaderOutputs — 编辑器保存在 Backboard 上的发布设置。fragment 不声明 Backboard，因此这些键放在这里，构建会据此合成一份。create --from-rev 会把 .rev 的 Backboard 写回这些键。

artboard — 生成画板时的默认尺寸和背景，仅在没有 .rml 时使用。尺寸默认为 800 x 800。background 接受 #RRGGBB 或 #AARRGGBB；# 是必需的，因此值必须加引号。CLI 无法读取的值会在无警告的情况下被丢弃，留下默认值 #FF1D1D1D。

artboards — 与 artboard 相同的设置，按画板分别指定。每项以布局脚本去掉 .luau 后的路径为键，因此 ui/panel.luau 是 ui/panel。

exclude — 完全不打包的路径。一项可以按精确路径匹配文件或目录、匹配目录下的所有内容，以及用与 excludeFromRev 相同的 * 和 ? glob 匹配文件。output.dir 会自动被排除。用它来保持扫描整洁。

excludeFromRev — 只从导出的 .rev 中丢掉匹配项。.riv 和预览窗口始终包含全部内容。四个类别：

类别	匹配依据
scripts	模块路径，适用于 Luau 和 WGSL
artboards	名称
assets	名称
contents	资源字节，保留资源引用但不嵌入

模式支持 *（任意一串字符，包括 /）和 ?（一个字符）。排除布局脚本也会丢掉它生成的画板。

libraries — 其他项目目录，它们的模块可以在本项目名称下导入：

local button = require('lib:shared_widgets/button')

依赖通过嵌套库解析；两个项目都依赖的同一个库只加载一次；循环依赖会报错。每个库还会在项目旁边导出自己的 .rev。

revFlavor — editable（默认）或 library。控制导出的 .rev 是作为普通编辑器文件打开，还是作为供其他文件导入的库。

push — projectId 和 fileId，是第一次 rive push 之后写回的绑定。--publish 询问是否加水印时会发送 push.fileId。不要手工编辑此属性。

output.dir — .riv 写出的位置。默认为 build。

logs.file — 只追加的交错日志，包含编译器问题、脚本 print 输出和系统消息。

logs.problems — 每次构建都会重写，开头是 # rive generation N | E errors, W warnings | OK|FAILED 这样的文件头，因此它始终描述恰好一次构建。围绕 CLI 编写脚本时，应读取这个文件。

两个 logs 键都没有默认值。省略它们就不会写出日志文件。rive create 会把两者都写入搭建好的 rive.yaml，指向 build/；只手写了 name 的 rive.yaml 不会有日志。

CLI 不认识的键会被忽略且不发出警告；artboards: 中命名了不存在脚本的条目也一样。拼错的键不会让构建失败。